home *** CD-ROM | disk | FTP | other *** search
/ Floppyshop 2 / Floppyshop - 2.zip / Floppyshop - 2.iso / diskmags / 0022-3.564 / dmg-0090 / sten.txt / gemdos.asc < prev    next >
Text File  |  1997-04-16  |  33KB  |  1,012 lines
  1.                              GEMDOS 
  2.                              ======
  3.  
  4. The ST operating system (TOS) is a mixture of an Atari  operating 
  5. system  and  Microsofts Graphic  Environment  Manager  (GEM),  ie 
  6. GEMDOS,  BIOS, XBIOS, AES routines. In theory any of the OS's can 
  7. control the system and may be mixed freely with each other. 
  8.  
  9. What  follows  are  as complete a set of GEMDOS calls  as  I  can 
  10. compile from the sources available to me and examples in both GFA 
  11. Basic and ASSEMBLER of how to call the routines.
  12.  
  13. It   should   be   noted   that   the   contents   of   registers 
  14. d0,d1,d2,a0,a1,a2  should  always be considered  to  be  trashed. 
  15. Output  from  the routines are normally held in  register  d0  on 
  16. return.
  17.  
  18. To call a routine from Assembler:
  19.  
  20.         move.n param,-(SP)    n=byte/word/long
  21.                               repeat above until all parameters
  22.                               have been passed.
  23.         move.w func#,-(SP)    function number
  24.         trap #1               call gemdos function
  25.         add.w   stack,  SP    return stack to its origional value
  26.                               if the function returns anything eg
  27.                               an  error code it will be  held  in 
  28.                               the register d.0
  29.  
  30. What  follows  are  two  examples of  using  GEMDOS  funtions  in 
  31. assembly language.
  32.  
  33. EXAMPLE 1:     
  34. ==========
  35. *       Print a string to the screen and wait for a key to be 
  36. *       pressed before returning.
  37.         
  38.         pea    mess  ,-(a7)       Push address of string onto stack
  39.         move.w   #$09,-(a7)       Print string (null terminated)
  40.         trap #$1                  Call GEMDOS #$09
  41.         add.l    #$06, a7         Square up stack
  42.  
  43.         move.w   #$07,-(a7)       Wait for key to be pressed
  44.         trap #$1                  Call GEMDOS #$07
  45.         add.l    #$02, a7         Square up stack
  46.  
  47.         move.w   #$00,-(a7)       Return to desktop.
  48.         trap #$1                  Call GEMDOS #$00
  49. *                                 No stack to square up
  50.  
  51.         
  52. mess    dc.b 27,69
  53.  
  54. *       27,69 = Clear screen and home cursor.
  55.  
  56.         dc.b 10,10,10
  57.  
  58. *       10,10,10 = Perform three line feeds.
  59.  
  60.         dc.b "  HI THERE! EASY ISN'T IT!",13,10,10
  61.         dc.b "ANY KEY TO RETURN TO DESKTOP",0
  62.  
  63. *       The message to be printed.
  64. *       13 = Carraige return.
  65. *        0 = End of message.
  66.         
  67.         end
  68.  
  69.  
  70. EXAMPLE 2:
  71. ==========
  72. *       Check to see if the printer is on-line
  73. *       and print an appropriate message.
  74.  
  75. *       Clear the screen for message.
  76.  
  77.         pea  clr   ,-(a7)      Clear the screen
  78.         move.w #$09,-(a7)      GEMDOS #$09
  79.         trap   #$01            call it,
  80.         add.l  #$06,  a7       square up stack.
  81.  
  82. *       Call #$11 checks to see if the printer is 
  83. *       on-line. It returns 0 in D.0 if not.
  84.  
  85.         move.w #$11,-(a7)      GEMDOS #$11
  86.         trap   #$01            call it,
  87.         add.l  #$02,  a7       square up stack.
  88.  
  89. *       Check returned value.
  90.  
  91.         tst.l d0              Test to see if zero.
  92.  
  93. *       Select appropriate message.
  94.  
  95.         bne  online           If not 0 printer is on.
  96.         pea  off ,-(a7)       Put offline mess. onto stack.
  97.         bra rest              Jump over next bit.
  98.  
  99. online  pea   on ,-(a7)       Put online mess. onto stack.
  100.  
  101. *       Print appropriate message.
  102.  
  103. rest    move.w #$09,-(a7)      GEMDOS #$09
  104.         trap   #$01            call it,
  105.         add.l  #$06,  a7       square up stack.
  106.  
  107. *       Request key-press when ready to return.
  108.  
  109.         pea  any   ,-(a7)      Return to calling rotine
  110.         move.w #$09,-(a7)      GEMDOS #$09
  111.         trap   #$01            call it,
  112.         add.l  #$06,  a7       square up stack.
  113.  
  114. *       On key-press return to calling routine.
  115. *       (In this case, the desktop).
  116.  
  117.         move.w #$01,-(a7)      GEMDOS #$01
  118.         trap   #$01            call it,
  119.         add.l  #$02,  a7       square up stack.
  120.  
  121. *       Return to desktop.
  122.  
  123.         move.w #$00,-(a7)      No error,
  124.         move.w #$4c,-(a7)      GEMDOS #$4c
  125.         trap   #$01            call it.
  126. *                              No stack to tidy.
  127.  
  128.  
  129. *       Messages to be printed.
  130. *       =======================
  131.  
  132. clr     dc.b  27,69,10,10,10,0
  133.  
  134. off     dc.b  "THE PRINTER IS OFF LINE.",13,10,10,0
  135.  
  136. on      dc.b  "OK! THE PRINTER IS ON LINE.",13,10,10,0
  137.  
  138. any     dc.b  "PRESS ANY KEY TO CONTINUE.",0
  139.                 
  140.         end
  141.  
  142. To call a routine from GFA Basic:
  143.  
  144. Either  use VOID GEMDOS(parameters) when the function returns  no 
  145. result  or  it isn't required.  Ret%  =  GEMDOS(parameters)  will 
  146. return the result nornally held in register D.0 in the variable.
  147.  
  148. The parameters are passed as in the following example of Func. 3C
  149.  
  150.   (Function number, parameters in reverse order to those listed)
  151.   (&H3C,L:addr,attr)
  152.  
  153. It is assumed that any parameter passed is WORD length (16  bits) 
  154. otherwise the length must be stated.  IE L: for a 32 bit word and 
  155. B: for a 8 bit word.
  156.  
  157. EXAMPLE 1
  158. =========
  159. '
  160. '    WHEN RUNNING THIS PROGRAM FROM THE GFA BASIC INTERPRETER
  161. '    IT WILL CAUSE THE MOUSE POINTER TO LOCK UP ON RETURN TO
  162. '    THE DESKTOP.
  163. '
  164. '    THE COMPILED VERSION OF IT IS OK!
  165. '
  166. '    I CAN ONLY ASSUME THAT RETURNING TO THE DESKTOP IN THIS
  167. '    MANNER FROM THE INTERPRETER DOES NOT TIDY THE STACK
  168. '    CORRECTLY. CAN ANYONE LET ME KNOW THE REAL REASON?
  169. '
  170. '
  171. '
  172. '
  173. '    NOTE! IN BASIC YOU MUST DEFINE THE STRING BEFORE TRYING
  174. '    TO DERTERMINE ITS STRAT POSITION...LOGICAL REALLY.
  175. '
  176. '    Message to be printed
  177. '    ---------------------
  178. Mess$=Chr$(27)+Chr$(69)+Chr$(10)+Chr$(10)+Chr$(10)
  179. Mess$=Mess$+" HI! THERE! EASY ISN'T IT!"+Chr$(13)+Chr$(10)+
  180.       Chr$(10)
  181. Mess$=Mess$+"ANY KEY TO RETURN TO DESKTOP"+Chr$(0)
  182. '
  183. '
  184. '    Print a message to the screen 
  185. '    -----------------------------
  186. Void Gemdos(9,L:Varptr(Mess$))
  187. '
  188. '
  189. '    Wait for a key to be pressed
  190. '    ----------------------------
  191. Void Gemdos(7)
  192. '
  193. '
  194. '    Return
  195. '    ------
  196. Void Gemdos(0)
  197. '
  198. '
  199. End
  200.  
  201. EXAMPLE 2
  202. =========
  203. '
  204. '    WHEN RUNNING THIS PROGRAM FROM THE GFA BASIC INTERPRETER
  205. '    IT WILL CAUSE THE MOUSE POINTER TO LOCK UP ON RETURN TO
  206. '    THE DESKTOP.
  207. '
  208. '    THE COMPILED VERSION OF IT IS OK!
  209. '
  210. '    I CAN ONLY ASSUME THAT RETURNING TO THE DESKTOP IN THIS
  211. '    MANNER FROM THE INTERPRETER DOES NOT TIDY THE STACK
  212. '    CORRECTLY. CAN ANYONE LET ME KNOW THE REAL REASON?
  213. '
  214. '
  215. '
  216. '    NOTE! IN BASIC YOU MUST DEFINE THE STRING BEFORE TRYING
  217. '    TO DERTERMINE ITS START POSITION...LOGICAL REALLY.
  218. '
  219. '    Messages to be printed
  220. '    ----------------------
  221. Cls$=Chr$(27)+Chr$(69)+Chr$(10)+Chr$(10)+Chr$(10)+Chr$(0)
  222. '
  223. Off$="THE PRINTER IS OFF-LINE."+Chr$(13)+Chr$(10)+Chr$(10)+
  224.       Chr$(0)
  225. '
  226. On$="OK! THE PRINTER IS ON-LINE."+Chr$(13)+Chr$(10)+Chr$(10)+
  227.      Chr$(0)
  228. '
  229. Any$="PRESS ANY KEY TO CONTINUE."+Chr$(0)
  230. '
  231. '
  232. '     Clear screen, home the cursor and print three blank lines
  233. '     ---------------------------------------------------------
  234. Void Gemdos(&H9,L:Varptr(Cls$))
  235. '
  236. '
  237. '     Get printer status. NB: st% holds status on return
  238. '     --------------------------------------------------
  239. St%=Gemdos(&H11)
  240. '
  241. '
  242. '     Act on value of st%
  243. '     -------------------
  244. If St%=0                       ! PRINTER OFF-LINE
  245.   Mess%=Varptr(Off$)
  246. Else                           ! PRINTER ON-LINE
  247.   Mess%=Varptr(On$)
  248. Endif
  249. '
  250. '
  251. '     Print appropriate message
  252. '     -------------------------
  253. Void Gemdos(&H9,L:Mess%)
  254. '
  255. '
  256. '     Print 'ANY KEY..' message
  257. '     -------------------------
  258. Void Gemdos(&H9,L:Varptr(Any$))
  259. '
  260. '
  261. '     Wait for keypress
  262. '     -----------------
  263. Void Gemdos(&H7)
  264. '
  265. '
  266. '     Return to desktop
  267. '     -----------------
  268. Void Gemdos(&H4C,0)
  269. '
  270. '
  271. End
  272.  
  273. Both Assembler and Basic examples are in the GEMDOS.EX folder  on 
  274. side one of this disc. They are in both ASCII and .PRG format.
  275.  
  276. Note  the different sizes of the resulting .PRG files  from  each 
  277. source.
  278.  
  279.  HERE IS THE COMPLETE LIST OF GEMDOS FUNCTIONS AND ERROR CODES  
  280.  =============================================================
  281.  
  282.             $00 - Terminate process (old form), p_term_o
  283.  
  284. PARAMETERS..NO   
  285. RESULT......NO
  286. STACK.......2
  287.  
  288. NOTES.......Terminates the current program, with a return code of 
  289.             0. Function 4C should be used instead of this one.
  290.  
  291. -----------------------------------------------------------------
  292.                                                                 
  293.             $01 - Read character from keyboard & echo, c_conin
  294.  
  295. PARAMETERS..NO
  296. RESULT......D0.L = key code
  297. STACK.......2
  298.  
  299. NOTES.......Waits  for  a  key to be pressed,  echos  it  to  the 
  300.             screen and returns its value.   The result is a  long 
  301.             word with the ASCII code in the  lower  8  bits,  the 
  302.             physical key code in bits 16-23 and all other bits 0.
  303.  
  304. -----------------------------------------------------------------
  305.  
  306.             $02 - Write character to screen, c_conout
  307.  
  308. PARAMETERS..WORD : Character
  309. RESULT......NO
  310. STACK.......4
  311.  
  312. NOTES.......Writes  the given character to the screen.  A 16  bit 
  313.             parameter is supported so bytes must be ANDed with FF
  314.             before  calling.  At the moment the upper 8 bits  are 
  315.             ignored.
  316.  
  317. -----------------------------------------------------------------
  318.                                                                 
  319.             $03 - Read character from auxiliary port, c_auxin
  320.  
  321. PARAMETERS..NO
  322. RESULT......D0.B = Character read
  323. STACK.......2
  324.  
  325. NOTES.......Waits  for a byte to be received from  the  auxiliary 
  326.             device. (RS 232 port).
  327.  
  328. -----------------------------------------------------------------
  329.  
  330.             $04 - Write character to auxiliary device, c_auxout
  331.  
  332. PARAMETERS..WORD : Character
  333. RESULT......NO
  334. STACK.......4
  335.  
  336. NOTES.......Sends a character out via the RS 232 port.  The upper 
  337.             8 bits should be set to 0 for  future  compatibility. 
  338.             See function 02.
  339.  
  340. -----------------------------------------------------------------
  341.  
  342.             $05 - Write character to printer, c_prnout
  343.  
  344. PARAMETERS..WORD : Character      
  345. RESULT......NO
  346. STACK.......4
  347. NOTES.......Sends a character out via the parallel printer  port. 
  348.             The upper 8 bits should be set to 0. See function 2.
  349.             Returns -1 if OK otherwise 0 after 30ms timeout.
  350.  
  351. -----------------------------------------------------------------
  352.  
  353.             $06 - Raw I/O to standard I/O, c_rawio 
  354.  
  355. PARAMETERS..WORD : Character for output or 00FF to read.
  356. RESULT......D0.W if 00FF passed.
  357. STACK.......4
  358.  
  359. NOTES.......If the character passed is 00FF then the keyboard  is 
  360.             scanned and the result returned in D0,  0 if there is 
  361.             no  key  being pressed.  Otherwise the  character  is 
  362.             printer to the screen.
  363.  
  364. -----------------------------------------------------------------
  365.  
  366.             $07 - Raw input from keyboard, c_rawcin
  367.  
  368. PARAMETERS..NO
  369. RESULT......D0.L = character read.
  370. STACK.......2
  371.  
  372. NOTES.......Waits  for a key to be pressed andreturns its  value. 
  373.             It is not echoed to the screen.
  374.  
  375. -----------------------------------------------------------------
  376.  
  377.             $08 - Read character from the keyboard, c_necin
  378.  
  379. PARAMETERS..NO
  380. RESULT......D0.L = character read.
  381. STACK.......2
  382.  
  383. NOTES.......Waits for a key to be pressed and returns its  value. 
  384.             The Control keys,  C/S/Q,  are  interpreted in  their 
  385.             usual  way.  ie  Ctrl-C aborts  the  program,  Ctrl-S 
  386.             pauses output and Ctrl-Q resumes output.
  387.             There is no echo to the screen.
  388.  
  389. -----------------------------------------------------------------
  390.  
  391.             $09 - Write a string to the screen, c_conws
  392.  
  393. PARAMETERS..LONG : Adress of string.
  394. RESULT......NO
  395. STACK.......6
  396.  
  397. NOTES.......The string must be terminated with a null char. ie 0.
  398.  
  399. -----------------------------------------------------------------
  400.  
  401.             $0A - Read edited string from keyboard, c_conrs
  402.  
  403. PARAMETERS..LONG : Address of input buffer.
  404. RESULT......NO
  405. STACK.......6
  406.  
  407. NOTES.......Before  this routine is called the first byte of  the 
  408.             buffer should be set to the size of the data  portion 
  409.             of  the  buffer.  On return the second  byte  of  the 
  410.             buffer contains the length of the string,  the string 
  411.             starts at the third byte. The control keys CTRL-C/H/I 
  412.             /J/M/R/U/X have their normal 'edit' meaning.
  413.  
  414. -----------------------------------------------------------------
  415.  
  416.             $0B - Check status of keyboard, c_conis
  417.  
  418. PARAMETERS..NO
  419. RESULT......D0.L = -1 if char available, 0 otherwise.
  420. STACK.......2
  421.  
  422. NOTES.......This only indicates whether a key is being pressed.
  423.  
  424. -----------------------------------------------------------------
  425.  
  426.             $0E - Set default drive, d_setdrv
  427.  
  428. PARAMETERS..WORD : Drive number.
  429. RESULT......D0.L = Bit map of drives in system.
  430. STACK.......4
  431.  
  432. NOTES.......Drives are numbered 0=A,  1=B....  The returned value 
  433.             has a bit set for each installed drive.
  434.  
  435. -----------------------------------------------------------------
  436.  
  437.             $10 - Check status of standard output, c_conos
  438.  
  439. PARAMETERS..NO
  440. RESULT......D0.L = -1 if ready, 0 if not.
  441. STACK.......2
  442.  
  443. NOTES.......Checks to see if console device is ready for  output. 
  444.             Currently always -1.
  445.  
  446. -----------------------------------------------------------------
  447.  
  448.             $11 - Check status of printer, c_prnos
  449.  
  450. PARAMETERS..NO
  451. RESULT......D0.L = -1 if ready, 0 if not.
  452. STACK.......2
  453.  
  454. NOTES.......Checks to see if the printer is on line.
  455.  
  456. -----------------------------------------------------------------
  457.  
  458.             $12 - Check status of serial port input, c_auxis
  459.  
  460. PARAMETERS..NO
  461. RESULT......D0.L = -1 if ready, 0 if not.
  462. STACK.......2
  463.  
  464. NOTES.......Checks the RS 232 port to see if there is a character 
  465.             waiting to be read.
  466.  
  467. -----------------------------------------------------------------
  468.  
  469.             $13 - Check status of serial port output, c_auxos
  470.  
  471. PARAMETERS..NO
  472. RESULT......D0.L = -1 if ready, 0 if not.
  473. STACK.......2
  474.  
  475. NOTES.......Checks  the  RS  232 port to see if it  is  ready  to 
  476.             receive a character.
  477.  
  478. -----------------------------------------------------------------
  479.  
  480.             $19 - Get default drive, d_getdrv
  481.  
  482. PARAMETERS..NO
  483. RESULT......D0.W = drive number.
  484. STACK.......2
  485.  
  486. NOTES.......Returns the current drive number, 0=A, 1=B...
  487.  
  488. -----------------------------------------------------------------
  489.  
  490.             $20 - Enter supervisor/user mode, s_super
  491.  
  492. PARAMETERS..LONG : Value for stack or 0 or -1.
  493. RESULT......D0.L = variable, see notes.
  494. STACK.......6
  495.  
  496. NOTES.......This can either tell you that the program is in  User 
  497.             or  Supervisor  mode  or it can switch  from  one  to 
  498.             another. To determine which mode the processor is in, 
  499.             call  the  function  with  a  parameter  of  -1.  The 
  500.             returned  value  will  be  0  for  user  and  1   for 
  501.             supervisor mode.  To switch modes a new stack pointer 
  502.             must be passed, or 0 if it is to remain unchanged, to 
  503.             the parameters.
  504.  
  505. -----------------------------------------------------------------
  506.  
  507.             $1A - Set disc transfer address, f_setdta
  508.  
  509. PARAMETERS..LONG : Pointer to disc transfer address.
  510. RESULT......NO
  511. STACK.......6
  512.  
  513. NOTES.......Sets  the  address  of  a 44  byte  buffer  used  for 
  514.             searching for filenames. Used by f_sfirst, No.4E.
  515.  
  516. -----------------------------------------------------------------
  517.  
  518.             $2A - Get date, t_getdate
  519.  
  520. PARAMETERS..NO
  521. RESULT......D0.W = date.
  522. STACK.......2
  523.  
  524. NOTES.......Reads the date and holds the results in the format:
  525.             bits 0-4  (1-31)      = day,
  526.             bits 5-8  (1-12)      = month,
  527.             bits 9-15 (1980-2100) = year.
  528.  
  529. -----------------------------------------------------------------
  530.  
  531.             $2B - Set date, t_setdate
  532.  
  533. PARAMETERS..WORD : Date.
  534. RESULT......NO
  535. STACK.......4
  536.  
  537. NOTES.......Same as function 2A.
  538.  
  539. -----------------------------------------------------------------
  540.  
  541.             $2C - Get time, t_gettime
  542.  
  543. PARAMETERS..NO
  544. RESULT......D0.W = Time.
  545. STACK.......2
  546.  
  547. NOTES.......Returns the time in format:
  548.             bits 0-4   (0-60-even) = seconds,
  549.             bits 5-10  (1-60)      = minutes,
  550.             bits 11-15 (0-24)      = hours.
  551.  
  552. -----------------------------------------------------------------
  553.  
  554.             $2D - Set time, t_settime
  555.  
  556. PARAMETERS..WORD : Time.
  557. RESULT......NO
  558. STACK.......4
  559.  
  560. NOTES.......Sets the current time. Format as function 2C.
  561.  
  562. -----------------------------------------------------------------
  563.  
  564.             $2F - Get disc transfer address, f_getdta
  565.  
  566. PARAMETERS..NO
  567. RESULT......D0.L = pointer to disc transfer address.
  568. STACK.......2
  569.  
  570. NOTES.......Should always be even. Address used by 4E.
  571.  
  572. -----------------------------------------------------------------
  573.  
  574.             $30 - Get version number, s_version
  575.  
  576. PARAMETERS..NO
  577. RESULT......D0.W = version number
  578. STACK.......2
  579.  
  580. NOTES.......Returns GEMDOS version number. The major number is in 
  581.             the low byte and the minor number is in the high byte.
  582.             $0D00 - ver. 0.13 (disc based).
  583.             $1300 - ver. 0.19 (ROM based).
  584.  
  585. -----------------------------------------------------------------
  586.  
  587.             $31 - Terminate and stay resident, p_termres
  588.  
  589. PARAMETERS..WORD : Exit code.
  590.             LONG : Bytes to keep.
  591. RESULT......NO
  592. STACK.......8
  593.  
  594. NOTES.......Allows  a program to terminate but also to remain  in 
  595.             memory.  This  is useful  for  those  programs  which 
  596.             expand the system such as screen dumps and ram discs.
  597.             The  memory which is retained is that  starting  from 
  598.             the  base page.  The length parameter should  include 
  599.             the  $100  bytes for the base page plus  the  program 
  600.             length and data and stack space if necessary.
  601.  
  602. -----------------------------------------------------------------
  603.  
  604.             $36 - Get drive free space, d_free
  605.  
  606. PARAMETERS..WORD : Drive code.
  607.             LONG : Pointer to buffer.
  608. RESULT......NO
  609. STACK.......8
  610.  
  611. NOTES.......Returns  information on a specified disc  drive.  The 
  612.             drive code is 0=default,  1=A, 2=B... etc. The buffer 
  613.             should be 16 bytes  and will have four long words  of 
  614.             information  placed in it.  These  are,  free  space, 
  615.             number of clusters,  sector size (bytes) and  cluster 
  616.             size (sectors).
  617.  
  618. -----------------------------------------------------------------
  619.  
  620.             $39 - Create a sub-directory, d_create
  621.  
  622. PARAMETERS..LONG : Address of pathname.
  623. RESULT......D0.W = 0 if OK, else error code.
  624. STACK.......6
  625.  
  626. NOTES.......This  will  create a new entry as defined by  a  null 
  627.             terminated string.
  628.  
  629. -----------------------------------------------------------------
  630.  
  631.             $3A - Delete a sub-directory, d_delete
  632.  
  633. PARAMETERS..LONG : Address of pathname
  634.  
  635. RESULT......D0.W = 0 if OK, else error code.
  636. STACK.......6
  637.  
  638. NOTES.......Deletes the directory if it contains no files.
  639.  
  640. -----------------------------------------------------------------
  641.  
  642.             $3B - Set current directory, d_setpath
  643.  
  644. PARAMETERS..LONG : Address of pathname
  645. RESULT......D0.W = 0 if OK, else error code.
  646. STACK.......6
  647.  
  648. NOTES.......Sets  the  current directory according  to  the  null 
  649.             terminated  string.  This trap may be  unreliable  on 
  650.             GEMDOS v0.13.
  651.  
  652. -----------------------------------------------------------------
  653.  
  654.             $3C - Create a file, f_create
  655.  
  656. PARAMETERS..WORD : Attributes.
  657.             LONG : Pointer to string.
  658. RESULT......D0.W = file handle if OK, else error coge (-ve).
  659. STACK.......8
  660.  
  661. NOTES.......Attempts  to  create a file.  If successful  it  will 
  662.             return  a  file  handle  for  use  by  other   GEMDOS 
  663.             functions. 
  664.             WORD can be :  1 = read only,
  665.                            2 = hidden file,
  666.                            4 = hidden system file,
  667.                            8 = filename contains volume  name  in 
  668.                            first 11 bytes.
  669.             The  file handle numbers returned start at 6  and  go 
  670.             upwards.  Handles from 0-5 are standard handles which 
  671.             are opened when a program starts. They are:
  672.                            0 = console input,
  673.                            1 = console output,
  674.                            2 = serial port,
  675.                            3 = parallel port,
  676.                            4 = undefined,
  677.                            5 = undefined.
  678.  
  679. -----------------------------------------------------------------
  680.  
  681.             $3D - Open file, f_oopen
  682.  
  683. PARAMETERS..WORD : Mode.
  684.             LONG : Pointer to filename.
  685. RESULT......D0.W = handle if OK, else error code (-ve).
  686. STACK.......8
  687.  
  688. NOTES.......Opens an existing file for reading,  writing or both. 
  689.             The mode word must be one of:
  690.             0 = open to read,
  691.             1 = open to write,
  692.             2 = open to read and write.
  693.             If  successful the function will return a  handle  as 
  694.             described in function 3C.
  695.  
  696. -----------------------------------------------------------------
  697.  
  698.             $3E - Close file, f_close
  699.  
  700. PARAMETERS..WORD : Handle.
  701. RESULT......D0.W = 0 if OK, else error code.
  702. STACK.......4
  703.  
  704. NOTES.......Closes files corresponding to the file handle.
  705.  
  706. -----------------------------------------------------------------
  707.  
  708.             $3F - Read file, f_read
  709.  
  710. PARAMETERS..LONG : Load address.
  711.             LONG : Number of bytes to read.
  712.             WORD : Handle.
  713. RESULT......D0.W = number of bytes read or error code (-ve).
  714. STACK.......12
  715.  
  716. NOTES.......Attempts  to read bytes from the given file.  If  the 
  717.             end  of the file is reached before all the bytes  are 
  718.             read no error code is returned. The bytes read should 
  719.             be compared with the number asked for.
  720.  
  721. -----------------------------------------------------------------
  722.  
  723.             $40 - Write file, f_write
  724.  
  725. PARAMETERS..LONG : Start address.
  726.             LONG : Bytes to write.
  727.             WORD : Handle.
  728. RESULT......D0.W = Number of bytes written, else error code(-ve).
  729. STACK.......12
  730.  
  731. NOTES.......Attempts  to write bytes to the given  file.  If  the 
  732.             disc becomes full before all the bytes are written no 
  733.             error code is given. Compare the bytes written to the 
  734.             bytes specified.
  735.  
  736. -----------------------------------------------------------------
  737.  
  738.             $41 - Delete file, f_delete
  739.  
  740. PARAMETERS..LONG : Pointer to filename.
  741. RESULT......D0.W = 0 if OK, else error code.
  742. STACK.......6
  743.  
  744. NOTES.......Attempts to delete the given file.
  745.  
  746. -----------------------------------------------------------------
  747.  
  748.             $42 - Seek file pointer, f_seek
  749.  
  750. PARAMETERS..WORD : Mode.
  751.             WORD : File.
  752.             LONG : Position.
  753. RESULT......D0.W = absolute position in file after seek.
  754. STACK.......10
  755.  
  756. NOTES.......Moves  a file pointer to a given position within  the 
  757.             file. The mode word is defined:
  758.             0 = move N bytes from start of file,
  759.             1 = move N bytes from current position,
  760.             2 = move N bytes from end of file.
  761.             If  the pointer is moved past either end of the  file 
  762.             the result is 0 or the file length.
  763.  
  764. -----------------------------------------------------------------
  765.  
  766.             $43 - Get or set file attributes, f_attrib
  767.  
  768. PARAMETERS..WORD : Attributes.
  769.             WORD : Get/set.
  770.             LONG : Pointer to filename.
  771. RESULT......D0.W = new attributes, else error code.
  772. STACK.......10
  773.  
  774. NOTES.......The attribute word should be set to one of:
  775.             $01 = read only,
  776.             $02 = hidden file,
  777.             $04 = hidden system file,
  778.             $08 = filename with volume name in 1st 11 bytes,
  779.             $10 = subdirectory,
  780.             $20 = file is written and closed.
  781.  
  782.             The get/set word is set to:
  783.             0 = to GET or 1 = to SET.
  784.  
  785. -----------------------------------------------------------------
  786.  
  787.             $45 - Duplicate file handle, f_dup
  788.             
  789. PARAMETERS..WORD : Standard handle.
  790. RESULT......D0.W = new handle, else error code.
  791. STACK.......4
  792.  
  793. NOTES.......Returns  a new handle that can be used to  address  a 
  794.             standard input device  (0-5),  May be closed  without 
  795.             affecting standard device handle.
  796.  
  797. -----------------------------------------------------------------
  798.  
  799.             $46 - Force file handle, f_force
  800.  
  801. PARAMETERS..WORD : Non-standard handle.
  802.             WORD : Standard handle.
  803. RESULT......D0.W = 0 if OK, else error code.
  804. STACK.......6
  805.  
  806. NOTES.......Forces  the  standard  handle to point  to  the  same 
  807.             device/file as the non-standard one.  A use would  be 
  808.             to re-direct screen output to a disc file.
  809.  
  810. -----------------------------------------------------------------
  811.  
  812.             $47 - Get current directory, d_getpath
  813.  
  814. PARAMETERS..WORD : Drive number.
  815.             LONG : Pointer to buffer.
  816. RESULT......D0.W = 0 if OK, else error code.
  817. STACK.......8
  818.  
  819. NOTES.......The current directory is returned in the given buffer 
  820.             ( in  null terminated format ) for  any  given  drive 
  821.             number,  A=0,  B=1, ... The buffer should be 64 bytes 
  822.             long.
  823.  
  824. -----------------------------------------------------------------
  825.  
  826.             $48 - Allocate memory, m_alloc
  827.  
  828. PARAMETERS..LONG : Number of bytes required.
  829. RESULT......D0.L = address of memory allocated. Failure = 0.
  830. STACK.......6
  831.  
  832. NOTES.......Allocates the given amount of memory from the  system 
  833.             pool, if available.  When a program terminates all of 
  834.             its  memory allocations are cleared.  This call  will 
  835.             also return the amount of free memory if-1 is passed.
  836.               
  837.             NOTE  -  This call will occasionally  return  an  ODD 
  838.             value for the start of the allocated memory.
  839. -----------------------------------------------------------------
  840.  
  841.             $49 - Free alloctaed memory, m_free
  842.  
  843. PARAMETERS..LONG : Address of area to free.
  844. RESULT......D0.W = 0 if OK, else error code.
  845. STACK.......6
  846.  
  847. NOTES.......Frees the bock of memory allocated by function $48.
  848.  
  849. -----------------------------------------------------------------
  850.  
  851.             $4A - Shrink allocated memory, m_shrink
  852.  
  853. PARAMETERS..LONG : Length to keep.
  854.             LONG : Start address to keep.
  855.             WORD : 0.
  856. RESULT......D0.W = 0 if OK, else error code.
  857. STACK.......12
  858.  
  859. NOTES.......Normally  used when a program starts and then has  to 
  860.             release part of the allocted memory back to GEMDOS.
  861.  
  862. -----------------------------------------------------------------
  863.  
  864.             $4B - Load or execute a program, p_exec
  865.  
  866. PARAMETERS..LONG : Pointer to evironment string.
  867.             LONG : Pointer to command line.
  868.             LONG : Pointer to filename.
  869.             WORD : Mode.
  870. RESULT......D0.L = depends on mode.
  871. STACK.......16
  872.  
  873. NOTES.......Used to RUN or CHAIN programs. Mode can be one of the 
  874.             following:  0 - Load and execute
  875.                         3 - Load but do not execute
  876.             For  0,  the return value is either an error code  or 
  877.             the value returned when the Child program is exited.
  878.             For 3,  the return value is either an error code or a 
  879.             pointer to the base page of  the loaded  program.  To 
  880.             subsequently pass control to the loaded program:
  881.  
  882.                     move.l d0,a0       ; pointer to base page
  883.                     jmp    $100(a0)    ; jump to it
  884.  
  885.             The environment string is usually a null string.
  886.  
  887. -----------------------------------------------------------------
  888.  
  889.             $4C - Terminate program, p_term
  890.  
  891. PARAMETERS..WORD : return value.
  892. RESULT......N/A - doesn't return.
  893. STACK.......N/A
  894.  
  895. NOTES.......Terminates the current program,  returning control to 
  896.             the parent program (Normally Desktop on the ST).  The 
  897.             word value returned should normally be an error  code 
  898.             ( 0  =  no error ).  Returned error codes  should  be 
  899.             positive  to  avoid confusion with system error codes
  900.             which  are negative.
  901.  
  902. -----------------------------------------------------------------
  903.  
  904.             $4E - Search for first, f_sfirst
  905.  
  906. PARAMETERS..WORD : Attributes.
  907.             LONG : Pointer to filespec.
  908. RESULT......D0.W = 0 if found, else -33 if not found.
  909. STACK.......8
  910.  
  911. NOTES.......Can  be used to scan a directory using  wildcards  to 
  912.             find all the files.  This function is called to  find 
  913.             the first one and $4F is used to find the rest.  When 
  914.             a  file is found the parameters are returned  in  the 
  915.             DTA buffer area.  The attribute word determines which 
  916.             file  types are to be included in the search and  may 
  917.             be one of:
  918.  
  919.               $00 - normal files
  920.               $01 - read only files
  921.               $02 - hidden files
  922.               $04 - system files
  923.               $08 - return volume name only
  924.               $10 - subdirectories
  925.               $20 files that have been written to and closed
  926.  
  927.             The returned values in the DTA buffer are:
  928.  
  929.                0-20   - reserved for internal use
  930.                21     - file attributes
  931.                22-23  - file time stamp
  932.                24-25  - file date stamp
  933.                26-29  - file size (long)
  934.                30-43  - name and extension of file (null termin.)
  935.  
  936.             The address of the DTA buffer may be set with $1A and 
  937.             read with $2F.
  938. -----------------------------------------------------------------
  939.  
  940.             $4F - Search for next occurence, f_snext
  941.  
  942. PARAMETERS..NONE.
  943. RESULT......D0.W = 0 if found, else -33 if not found.
  944. STACK.......2
  945.  
  946. NOTES.......After  calling $4E to find the first occurence  of  a 
  947.             filespec this call is used to find subsequent  files. 
  948.             When  a file  is found the DTA buffer  is  filled  as 
  949.             described  previously.  For it to work the  first  20 
  950.             bytes  of  the  DTA  buffer   must  remain  unaltered 
  951.             between calls.
  952.           
  953. -----------------------------------------------------------------
  954.  
  955.             $56 - Rename a file, f_rename
  956.  
  957. PARAMETERS..LONG : Pointer to new name.
  958.             LONG : Pointer to old name.
  959.             WORD : 0
  960. RESULT......D0.W = 0 if OK, else error code.
  961. STACK.......12
  962.  
  963. NOTES.......Will  attempt to rename the old file to that  of  the 
  964.             newname. A file of the newname must not already exist.
  965.  
  966. -----------------------------------------------------------------
  967.  
  968.             $57 - Get/set file date and time stamp
  969.  
  970. PARAMETERS..WORD : 0=set 1=get.
  971.             WORD : File handle.
  972.             LONG : Pointer to buffer.
  973. RESULT......NONE.
  974. STACK.......10
  975.  
  976. NOTES.......May be used to get or set the time and date stamp  on 
  977.             an  open file.  The buffer should contain two  words, 
  978.             the  first  being the time and the second  being  the 
  979.             date in the format described previously.
  980.  
  981.  
  982. ERROR CODES
  983. ===========
  984.  
  985. ERROR     PCDOS     SUPPORTED                     NOT SUPPORTED
  986. CODE      EQUIV.    
  987.  
  988.  -32        1       Invalid function number
  989.  -33        2       File not found
  990.  -34        3       Path not found
  991.  -35        4       No handles left (Too many files open)
  992.  -36        5       Access denied
  993.  -37        6                                     Invalid handle
  994.  -38        7
  995.  -39        8       Insufficient memory
  996.  -40        9                                     Invalid memory
  997.                                                   block address
  998.  -41       10       Insufficient memory
  999.  -42       11       Insufficient memory
  1000.  -43       12
  1001.  -44       13
  1002.  -45       14       
  1003.  -46       15       Invalid drive specification
  1004.  -47       16       Invalid operation
  1005.  -48       17
  1006.  -49       18       No more files
  1007.  
  1008. Next  to  get  the  same treatment will be  the  BIOS  and  XBIOS 
  1009. functions. DAVE MOONEY
  1010.  
  1011.  
  1012.